Portable locomotion Beta 1:

By: Chicago Locomotive Works



Before we go any further, Read this document. Get familiar with the tool before you use it. It can possibly screw up your locomotion install. 

Make sure you read the known issues at the bottom.

The "intended use" of this program is a simple mod for all users.

The "advanced uses" are advanced and not for all users.

This is still beta and god knows what can go wrong still. It would be a good idea to back up your Locomotion folder to a DVD or zip file now. 



******************
What it is:
******************

This is a simple little script that allows you to play Locomotion in a way it was not intended to run; 

To run off of a thumb drive without installing it on the host system.

******************
Why Do I need this?:
******************

You don't. 

I did. I made it for myself and I am just offering it to you to use. Maybe you have a use for this, maybe you don't. I know some of my friends did.


******************
What it does:
******************

It allows you to copy Your Locomotion game folder to a Thumb Drive and play it from the thumb drive. It will also allow you to plug the Thumb drive into PC that has has another Locomotion install on it, not effecting that install*. It will also work on a system that has never had locomotion installed on it.

Now you can play on you spare PC with Your custom Objdata and all of your save games/scenarios. Take it to the library, Take it to school, Take it to the office, Ect.

******************
Side effects that work to your advantage:
******************

You may now have a second (or more) locomotion install(s) on one PC. This would allow you to have your main locomotion setup, plus perhaps a second install that is virgin for creating maps. Perhaps you wanted a setup that is just German packs and has the German station Mod.

When playing from a Thumb Drive and You exit properly (see Issues), you will leave no trace behind that you even played LoMo on that system.**

(Good for sneaking a game in when your IT dept./Parents are not paying attention).



******************
Why I did this:
******************

I did this for 2 reasons.

*****
The Second Reason (and the actual reason I made this); I was installing windows XP on an Asus 701 4g netbook*** for a friend. I wanted to test locomotion on this device. Since it has No hard drive (just a 4 GB flash drive for the hard drive) and no CD drive, I was forced to try it this way.

*****
The first reason (that I was just too lazy to try researching this for);

 I wanted to have more than one working copy of Locomotion on My PC. 

This allowed me to work on my US set and not worry about getting LoMo crashes from other Sets/scenarios installed.

In addition, with the price of thumb drive becoming cheaper every day, This was a great way for me to make a custom copy of locomotion for any scenario that I am currently playing and taking it and my save games with me all time as I constantly play from different PC's.

*****
OK, a third. The 3000 dat limit; 

Not everyone is aware of the 3000 dat limit. While it is not hard coded or set in stone the maximum number of dats allowed in your Objdata folder (at the time of writing this). Many people are posting bizarre issues in game as they reach or just pass this number of dats. While some people have passed this number (so they claim), many have not. By allowing to have more than one install, it is easier to overcome this obstacle. 

you can also use a "Portable Install" to test new downloads. copy your portable folder, install the new dats and test them. delete the  whole Portable Install after testing. you can then install to another permanent  home if the test went well (or not delete the new folder if it was a large enough set).   

*****
hrmm a Fourth. The Scenario bug; 

Another little known bug in Locomotion. the Scenario bug. Locomotion checks every scenario in your scenario folder and adds all the dats to the database. This can lead to LoMo tossing errors.

 When you download a scenario and place it in your "Scenario" folder, then you start a new or edit an existing scenario. If you do not have all the mods in that downloaded scenario, your Scenario editor will crash when it cannot find the expected dat from the downloaded map in the Objdata folder. If you are lucky, only your scenario editor is now broken. If you are unlucky, LoMo will no longer start. The same happens if you create a map and then delete some mods from your Objdata folder.

 This is not a great example of this tool, but you can use it to team up different "portable installs" with certain scenarios that You like or love. A better example, a friend gave me his entire Objdata to play with a save game he made. Great save game. Terrible Objdata for my use 575Mb and 2910 dats. I "Portabled" it.

*****
Oh man, A fifth. Online play;
If you have a different setup for playing online with your friends. You can have a Multiplayer Portable Install (see notes about multiplayer license issues).


******************
How it works:
******************

First, how does Locomotion work; Locomotion has registry keys that tell it how to act and behave. 

Because these keys are set in stone, it prevents several basic things. The biggest being able to have two installs of the game on one PC. When you start Loco.exe from a second install, it always uses the primary folder set (DATA,OBJDATA,SCENARIOS,SAVE,Etc.) That is stored in the registry. This problem renders the second install totally useless.

Now, how does this work;

It uses a simple scripting system. It grabs the registry information from the Host PC for Locomotion. It makes a quick copy of it. It then plugs in the needed data for the Portable Locomotion to start. It then starts the Portable Locomotion. As locomotion is loading, in the background, it waits a few seconds (5000 MS?), then it restores all of the backed up data to the host. Long enough to start lomo and for it get all the information it needs. In the cases where there were no previous entries for Locomotion, it removes the entries completely.


******************
What do I need use it?:
******************

1. You need an installed licensed copy of Locomotion. (for your source folder)
2. You Need a thumb drive (if you are going portable) 
3. you need the program itself.
4. You need a NOCD patch. (sorry. I can't help you find it. I'll add CD checking support in the future. but, that defeats the purpose of "portable".)
5. [optional - recommended] the Locomotion Music removing tool. (saves about 340MB off the thumb drive install)
6. You need to review your EULA and local governing media rights laws to make sure you are not breaking any laws. It is possible you might have to uninstall the version on your desktop to stay 100% legal.

******************
How do I use it?:
******************

Ah yes, probably the first question asked.

Simple...

#1 Review Your EULA from Chris Sawyer, Take care not to Violate it.

#2 take your Locomotion install, copy it to your thumb drive (or another folder). you need to take the entire "Locomotion" folder and all [original] files in it.
*** for US set users, do not take the "Chicago_Locomotive_Works" folder!!****
*** for locobrowser(2) users, do not take all of the Objdata sub-folders!!****

#3 Place the Portable Locomotion launcher into the same folder as Loco.exe. You do not need the portable.ini, the program will make a new copy of it with the correct data. 

#4 USE THE PORTABLE LOCOMOTION to start Locomotion.

#5 Confirm it worked! hit "load saved game" and verify the path is indeed your portable folder set. (J:\Portable_Locomotion as an example.) 

#6 Read step 5 again.

#7 Enjoy this awesome game.

*****

read the other instructions first.

Intended use Step by Step:

1. Create a new folder 
	[can be on the thumb drive itself. I prefer on the HDD for speed]

2. Name it something descriptive of what it will be.
	"Portable LoMo with US Set" for example.

3. Copy (not move) the following 7 items to the new folder.
 
	#1 Data [Folder] Do not take any subfolders!!

	#2 Objdata [Folder] Do not take any subfolders!!

	#3 Scenarios [Folder] Do not take any subfolders!!

	#4 Single Player Saved Games [Folder] Do not take any subfolders!!

	#5 Two Player Saved Games [Folder] Do not take any subfolders!!

	#6 LOCO.EXE [The program]

	#7 README.txt [The EULA]

4. Copy the NOCD patch to this folder [Yes to overwrite]

5. Copy the Portable Locomotion exe to this folder.

6. [optional] Rip the music out.

7. [optional] Rip the scenarios out you dont need. (You MUST leave "Boulder Breakers" or LoMo crashes)

8. Add any additional mods you want. [Test it with the launcher if you like]

9. MOVE this folder to your thumb drive. [If it is not already]

10. Test it out confirming it started in the right folder.




******************
A few possible Ideas: How do I use it? Continued...
******************

Intended use:

#1 Copy Your locomotion folder to your thumb drive, add the  portable launcher, take it with you on the road. (Possibly removing the music files to save space. [See advanced use]) 

Advanced Uses:
(Not for everyone)

#1 Install a fresh copy of locomotion. ERASE ALL LEFTOVER FILES IN THE LOCOMOTION FOLDER.  Copy the folder to a new location and rename it something like "Modded Locomotion" or "Portable Locomotion" or "Locomotion_Modded_with_BRset" then install your mods to this new folder. Leaving your default install alone.

One reason I suggest leaving the default version virgin; if you ever reinstall, that is the one that gets erased by the uninstaller.

#2 install Locomotion add all your mods to it. Get it just the way you want it. Then make a copy of it or rename it. Give it a new name like "My_fovorite_Locomotion_set" or "My favorite locomotion set".
Then reinstall locomotion. It should erase the master version, not the copy you just made.

#3 follow one of the above methods making an install for each way you like to play, maybe "BR_SET_Lomo" and a "US Set LoMo",

#4 Use my "Locomotion Repacker" To quickly build sets for making a portable version.

#5 dealing with the HUGE DATA folder: this can eat up a lot of hard drive space quickly. Most of this folder is the music files. I recommend using the music stripper tool to remove the music, especially on thumb drive installs.
 

******************
Known or Possible Issues:
******************

#Starting for the first time after adding new mods:

Locomotion has to rebuild the database when you change something in the Objdata. This is very time consuming on slower systems, Large Objdata folder, running from USB1.0, etc. 
Because I only give it 5000ms(ish) to boot, it is possible it can throw an error, ask for a CD, or start the default locomotion. It has not happened to me yet in testing. I tried to get it to happen on an old laptop over USB 1.1.

If this happens, just exit and restart. Now that it has rebuilt the database, it should boot quickly. It is rare that this happens, but it is a possibility. 


#Installing set/packs to the "Portable Locomotion" folder:

If a pack reads the registry path for the setup, it might point to the wrong folder.
Pay attention when installing. Especially on any packs that I created..... (If someone runs into a pack that I made that WONT install to a portable properly let me know)


#Windows Vista UAC:

Vista UAC Support Added. Admin Elevation Requiered due to registry writes.


#Multiplayer:

There are some Issues with License keys for Multiplayer. 

This is fixable. I chose not to support it at this time. Since there is a potential for misuse. There is also a potential To accidently erase a CD Key if you  abort the program while it is running. As of right now, It uses the "Host Systems" CD Key. If Requested, I could possibly add support as there are legitimate needs for this now as "Net Books" become more popular.


#USB 1.1:

While most of us have USB2.0, This does run on USB 1.1. It is a little slow to load. Incredibly slow if you install the entire US Set at once and run for the first time (go get a drink or something). Once you get going, it seems to be OK. (I have not played a heavy game yet on 1.1)


#Play from CD/DVD:

NO!NO!NO! Don't even try it! I am not sure what LoMo will do because it needs to write data to the DATA folder during play. My script also needs to write to the Exe  folder. If it can't, I am Pretty sure My script will do something bad to your registry. (I tried to code in a failsafe for this, I am not wasting a CD to test it) 

After testing this from a backup DVD, Lomo itself throws an error.
"Game can not be played from CD" or something of that nature.


#Exit Properly:

let the program run for a few seconds after You start it (It will close the CLW image on its own when done). If You don't follow this critical step, it will leave the Temp data behind causing issues for other Locomotion installs.

Note... There is a failsafe check built in case something does go wrong (thumb drive falls out, power failure, earthquake, or God). just re-run the program and follow the instructions for recovery.


#Anti-Virus/Spyware:

So far I have gotten no "Alerts" from anything as a "suspicious program"


#Reinstallation:

Be careful before you reinstall. I tried to take into account most things that can go wrong. In the end, stuff does break. before you reinstall, make a check at what the uninstaller thinks is your LoMo folder. I would hate to have it uninstall your favorite set on accident.


#Removing your thumb drive while playing:

Don't laugh, someone will do this! the games plays fine for a bit (with the music off at least). It will eventually just exit with no error and no chance to save.


#Locomotion tools:

I have not tested any yet. I can see a few problems since they read the registry to find locomotion. Locomod and LocoSSA are prime examples of programs that will fail as it reads the locomotion registry before the game starts. I?ll have to code support in for those in the future. 

Until I do.. if you are fast, you can Alt-Tab LoMo as it starts and launch the tool before the launcher exits.

#File Associations:
File associations do not work. You cannot double click a save game to start Portable Locomotion.


#Operating Systems:
So far this has been tested on WIN XP pro SP2 and SP3, Vista Ultimate SP1 (with UAC off) Win Vista Ultimate 64Bit, Win 2003 SP2, Win 2008 R2, Win 7, Win 7 64Bit.

*this assumes that you don't start the program then rip your thumb drive out in the first 10 seconds. If you do, you might have issues. See above.

** assuming that you don't have software running that logs registry writes.

*** Asus 701 4G netbook has only a 4gig Flash drive for a hard drive. After installing XP and Office, there was not much room left for locomotion.  



Change log:

1.0 beta:

All new.

1.1:
UAC support
Freindlier wait time
Added CLW popup so you know when it is on.

1.2:
Upgraded code to be Windows 7 64bit compliant.
removed the bug that if you "clicked off" the CLW Splash, It ended the portable checking in the program.


Future plans?

it is quite possible that I will remake this program in Visual Studio with a lot more options. possibly for a fulltime portable/multi folder install support.

Two versions. This one being a "light" version and a heavy full featured version in the future.
